Skip to content

fix(mcp): clarify request wrapper in list_datasets, list_charts, list_dashboards#39920

Open
aminghadersohi wants to merge 5 commits intoapache:masterfrom
aminghadersohi:fix/mcp-list-datasets-schema-request-wrapper
Open

fix(mcp): clarify request wrapper in list_datasets, list_charts, list_dashboards#39920
aminghadersohi wants to merge 5 commits intoapache:masterfrom
aminghadersohi:fix/mcp-list-datasets-schema-request-wrapper

Conversation

@aminghadersohi
Copy link
Copy Markdown
Contributor

SUMMARY

LLMs consistently call list_datasets (and related list tools) with flat
top-level kwargs like search, page, page_size instead of wrapping them
in the required request object, resulting in pydantic validation errors:

pydantic_core.ValidationError: 4 validation errors for call[list_datasets]
  request: Missing required argument
  search: Unexpected keyword argument
  page: Unexpected keyword argument
  page_size: Unexpected keyword argument

This PR makes the calling convention explicit in the tool docstrings and
improves filter column descriptions to enumerate valid values.

Changes:

  • Add docstring usage examples to list_datasets, list_charts, and
    list_dashboards showing the correct request={...} call shape, with
    an explicit warning that flat kwargs are rejected
  • Enumerate valid col values directly in DatasetFilter, ChartFilter,
    and DashboardFilter field descriptions (e.g. created_by_fk is not a
    valid dataset filter column)
  • Add TestListDatasetsRequestWrapper unit tests covering: correct wrapper
    usage, defaults, valid/invalid col validation, and the flat-kwargs
    rejection scenario
  • Allow E501 in list_*.py tool files in ruff config (docstring examples
    with full request shapes exceed the 88-char limit)

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A — docstring and schema description changes only.

TESTING INSTRUCTIONS

  1. Run the new unit tests:
    pytest tests/unit_tests/mcp_service/dataset/tool/test_dataset_tools.py::TestListDatasetsRequestWrapper -v
  2. Inspect the updated docstrings in list_datasets, list_charts,
    list_dashboards — the IMPORTANT block and example usage should be
    clearly visible.

ADDITIONAL INFORMATION

  • Has associated issue:
  • Required feature flags:
  • Changes UI
  • Includes DB Migration
  • Introduces new feature or API
  • Removes existing feature or API

…ts, list_dashboards

LLMs consistently passed flat kwargs (search, page, page_size) to list_*
tools instead of wrapping them in the required `request` object, causing
pydantic validation errors.

- Add docstring usage examples to list_datasets, list_charts, and
  list_dashboards showing the correct `request={...}` call shape and
  explicitly warning against flat kwargs
- Enumerate valid filter columns directly in DatasetFilter, ChartFilter,
  and DashboardFilter field descriptions (e.g. `created_by_fk` is not a
  valid dataset filter col)
- Add TestListDatasetsRequestWrapper tests covering: correct request
  wrapper usage, default values, valid/invalid filter col validation,
  and the flat-kwargs rejection scenario from story #105712
- Allow E501 in list_*.py tool files (docstring examples need full request
  shapes to be instructive)
@codecov
Copy link
Copy Markdown

codecov Bot commented May 6, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.87%. Comparing base (5b5dd01) to head (0ea59cb).
⚠️ Report is 7 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master   #39920      +/-   ##
==========================================
- Coverage   63.88%   63.87%   -0.01%     
==========================================
  Files        2583     2583              
  Lines      136604   136625      +21     
  Branches    31502    31504       +2     
==========================================
  Hits        87276    87276              
- Misses      47812    47833      +21     
  Partials     1516     1516              
Flag Coverage Δ
hive 39.37% <ø> (-0.02%) ⬇️
mysql 59.04% <ø> (-0.02%) ⬇️
postgres 59.11% <ø> (-0.02%) ⬇️
presto 41.07% <ø> (-0.02%) ⬇️
python 60.55% <ø> (-0.03%) ⬇️
sqlite 58.75% <ø> (-0.02%) ⬇️
unit 100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@aminghadersohi aminghadersohi marked this pull request as ready for review May 7, 2026 02:38
@dosubot dosubot Bot added the change:backend Requires changing the backend label May 7, 2026
@aminghadersohi aminghadersohi requested a review from Copilot May 7, 2026 02:39
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR reduces recurring MCP tool invocation errors by making the required request={...} wrapper explicit in the list_datasets, list_charts, and list_dashboards tool docstrings, and by clarifying/validating allowed filter columns in the corresponding Pydantic schemas.

Changes:

  • Added prominent docstring guidance + examples showing the required request={...} call shape (and warning that flat kwargs are rejected).
  • Updated DatasetFilter/ChartFilter/DashboardFilter field descriptions to enumerate valid col values.
  • Added unit tests focused on the list_datasets request-wrapper/validation scenario, and added a Ruff per-file ignore for E501 in list_*.py tool modules.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
tests/unit_tests/mcp_service/dataset/tool/test_dataset_tools.py Adds tests for request-wrapper expectations and invalid filter column validation.
superset/mcp_service/dataset/tool/list_datasets.py Adds an IMPORTANT docstring block and example call shapes for request={...}.
superset/mcp_service/dataset/schemas.py Clarifies allowed DatasetFilter.col values in schema field description.
superset/mcp_service/dashboard/tool/list_dashboards.py Adds docstring guidance/examples for request-wrapped parameters.
superset/mcp_service/dashboard/schemas.py Clarifies allowed DashboardFilter.col values in schema field description.
superset/mcp_service/chart/tool/list_charts.py Adds docstring guidance/examples for request-wrapped parameters.
superset/mcp_service/chart/schemas.py Clarifies allowed ChartFilter.col values in schema field description.
pyproject.toml Adds Ruff per-file ignore for E501 in MCP list_*.py tool files to accommodate long docstring examples.

Comment thread tests/unit_tests/mcp_service/dataset/tool/test_dataset_tools.py
Comment thread tests/unit_tests/mcp_service/dataset/tool/test_dataset_tools.py
- Fix test_sortable_columns_in_docstring: assertion used plain-text match
  but docstring now uses RST backtick format; use substring check for both
  'Sortable columns for' and 'order_column' separately
- Fix test_dataset_filter_valid_col: opr='ct' is not a valid
  ColumnOperatorEnum value; use opr='sw' (starts-with) instead
- Add test_request_wrapper_enforced_by_tool: exercises the wrapper pattern
  through the actual FastMCP client call (not just schema instantiation),
  verifying the MCP tool layer accepts request={...} correctly
- Strengthen test_flat_kwargs_rejected: assert that the ToolError message
  references the unexpected arguments ('search', 'Unexpected', or 'request')
  so the test cannot pass on unrelated failures
Comment thread superset/mcp_service/dataset/tool/list_datasets.py Outdated
Comment thread superset/mcp_service/chart/tool/list_charts.py Outdated
Comment thread superset/mcp_service/dashboard/tool/list_dashboards.py Outdated
…oard docstring test

- Replace opr:"ct" with opr:"sw" in filter examples in list_datasets,
  list_charts, and list_dashboards docstrings — "ct" is not a valid
  ColumnOperatorEnum value, so examples using it produce validation errors
- Fix TestDashboardSortableColumns.test_sortable_columns_in_docstring:
  assertion checked for "Sortable columns for order_column:" (plain text)
  but docstring uses RST backtick format; split into two substring checks
  matching "Sortable columns for" and "order_column" separately
@bito-code-review
Copy link
Copy Markdown
Contributor

bito-code-review Bot commented May 7, 2026

Code Review Agent Run #0d41fd

Actionable Suggestions - 0
Review Details
  • Files reviewed - 9 · Commit Range: 71f210c..c57de66
    • pyproject.toml
    • superset/mcp_service/chart/schemas.py
    • superset/mcp_service/chart/tool/list_charts.py
    • superset/mcp_service/dashboard/schemas.py
    • superset/mcp_service/dashboard/tool/list_dashboards.py
    • superset/mcp_service/dataset/schemas.py
    • superset/mcp_service/dataset/tool/list_datasets.py
    • tests/unit_tests/mcp_service/dashboard/tool/test_dashboard_tools.py
    • tests/unit_tests/mcp_service/dataset/tool/test_dataset_tools.py
  • Files skipped - 0
  • Tools
    • Whispers (Secret Scanner) - ✔︎ Successful
    • Detect-secrets (Secret Scanner) - ✔︎ Successful
    • MyPy (Static Code Analysis) - ✔︎ Successful
    • Astral Ruff (Static Code Analysis) - ✔︎ Successful

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

  • /review - Manually triggers a full AI review.

  • /pause - Pauses automatic reviews on this pull request.

  • /resume - Resumes automatic reviews.

  • /resolve - Marks all Bito-posted review comments as resolved.

  • /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

AI Code Review powered by Bito Logo

…port

All 6 new test methods in TestListDatasetsRequestWrapper were missing
the required -> None return type annotation (Rule 12). Also remove the
inline `from fastmcp.exceptions import ToolError` in test_flat_kwargs_rejected
since ToolError is already imported at module top-level (line 27).
@netlify
Copy link
Copy Markdown

netlify Bot commented May 7, 2026

Deploy Preview for superset-docs-preview ready!

Name Link
🔨 Latest commit c5b4fd7
🔍 Latest deploy log https://app.netlify.com/projects/superset-docs-preview/deploys/69fcb5aec0e0f600088929ee
😎 Deploy Preview https://deploy-preview-39920--superset-docs-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

change:backend Requires changing the backend size/L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants